Shareware Grab Bag

home *** CD-ROM | disk | FTP | other *** search

/ Shareware Grab Bag / Shareware Grab Bag.iso / 081 / xlatrgen.arc / XLATLIST.DOC < prev next >

Wrap

Text File | 1987-12-16 | 63KB | 1,681 lines

XlatList and RouteGen User's Manual Copyright 1985,86,87 by System Enhancement Associates, Inc. ALL RIGHTS RESERVED TABLE OF CONTENTS _______ ____ Section Page Introduction .................................................... 1 License ......................................................... 1 XlatList ........................................................ 2 XlatList control file ........................................... 3 Your own network address ..................................... 3 Country ...................................................... 3 Mode of operation ............................................ 3 User directory ............................................... 4 Forcing user directory entries ............................... 4 Node list report ............................................. 5 Node list report index ....................................... 5 Summary report ............................................... 5 Comments report .............................................. 5 Dashes in phone numbers ...................................... 6 Routing data files ........................................... 6 Processed node list .......................................... 6 Point net gateways ........................................... 6 Maximum baud rate ............................................ 6 Private node lists ........................................... 7 Public node lists ............................................ 7 Automatic cleanup ............................................ 8 SEAdog node list prefixes .................................... 8 Inserting phone numbers ...................................... 8 Inserting baud rates ......................................... 8 Inserting nets from other zones .............................. 9 Telephone dialing instructions ............................... 9 The cost table ............................................... 10 Multiple input files ......................................... 11 Command line arguments ....................................... 11 Multiple zones .................................................. 12 RouteGen ........................................................ 13 Lists of nodes .................................................. 16 Predefined macros ............................................... 16 By network or region ......................................... 16 By area code ................................................. 16 By country code .............................................. 17 By node list flags ........................................... 17 By routing hub ............................................... 17 By a list in a file .......................................... 17 By baud rate ................................................. 18 By real address .............................................. 18 Everybody! ................................................... 18 Except! ...................................................... 19 RouteGen Control Verbs .......................................... 20 Your own network address ..................................... 20 Mode of operation ............................................ 20 Multiple output files ........................................ 20 Multiple input files ......................................... 20 Defining your own macros ..................................... 21 Defining BIG macros .......................................... 21 Different schedules .......................................... 21 Displaying a list ............................................ 21 Writing a list to a file ..................................... 21 Conditionals ................................................. 21 More on conditional statements .................................. 23 Node list size limits ........................................... 24 Warranty ........................................................ 26 INTRODUCTION INTRODUCTION XlatList and RouteGen are utilities to assist system operators XlatList (sysops) in making use of St. Louis format node lists. XlatList is used to translate a St. Louis format node list into useable form. RouteGen RouteGen is used in conjunction with XlatList to assist in the creation of routing files. Each of these utilities is capable of functioning in any one of three SEAdog Fido Opus modes: SEAdog mode, Fido mode, and Opus mode. The differences will be described where applicable. LICENSE LICENSE XlatList and Routegen are the copyrighted property of System Enhancement Associates, Inc. You are granted a limited license to use them, and to copy and distribute them, provided that the following conditions are met: 1) No fee may be charged for such copying and distribution. 2) They may ONLY be distributed in their original, unmodified state. ___ 3) They may not be distributed, in whole or in part, as part of any commercial product or service without the express written permission of System Enhancement Associates, Inc. Contributions for the use of these programs will be appreciated, and should be sent to: System Enhancement Associates, Inc. 21 New Street, Wayne NJ 07470 You may not use these products in a commercial environment or a governmental organization without paying a license fee of $35. Site licenses are available. XlatList and RouteGen Page 1 XLATLIST XLATLIST XlatList is a "predigester" for the St. Louis format node list which turns it into a node list usable by SEAdog, Fido, or Opus. It looks on disk for a file of the name "NODELIST.nnn", where "nnn" is some number. If it finds more than one such file, then it picks the one with the highest number. For example, if you have four files on disk named: NODELIST.312 NODELIST.319 NODELIST.326 NODELIST.BBS Then XlatList will read NODELIST.326, and ignore the others. In fact, you should be careful about this just after New Year's Day. St. Louis format node lists use the julian date for the extension, so XlatList will almost always pick the proper one. But at the start of the year the numbering starts over at 001. If you have any older node lists lying around, XlatList will pick the oldest list from the previous year, which probably isn't what you want. If you have one or more NODEDIFF.nnn files on your disk, then XlatList will select the one with the highest number and attempt to apply it to the selected nodelist, in hopes of making a new node list file to use. For example, if you have five files on disk named: NODELIST.312 NODELIST.319 NODEDIFF.319 NODEDIFF.326 NODELIST.BBS Then XlatList will try to apply the changes in NODEDIFF.326 against the data in NODELIST.319 in an attempt to create NODELIST.326. If it succeeds, it will scan the newly created NODELIST.326. Otherwise, it will scan NODELIST.319. If the difference file includes a CRC check (given as a decimal number following a colon on the first line), then XlatList will compute a CRC value for the created node list and compare it with the CRC value given in the difference file. If they differ, then it will print an error message, and insert warnings at the end of the node list reports and at the beginning of the created NODELIST.BBS file (if any). XlatList is controlled primarily by its own control file, which is named "XLATLIST.CTL". This file is free-format text, and can be created with any normal text editor (such as EDLIN). A semicolon anywhere in the file marks the start of a comment, and everything from the semicolon to the end of the line is ignored. ___ XlatList is not case sensitive. Anything in its control file or in the node list or any of its arguments may be given in either uppercase or lowercase or a combination of the two. SEAdog Page 2 XlatList Following is a description of the possible statements that you can put in a XlatList control file: NODE <zone>:<net>/<node> NODE <zone>:<net>/<node> This tells XlatList what your network address is. This is especially required if your node list contains multiple zones, as XlatList will need to know what zone you are in. This is also used to determine the default network number for use elsewhere. COUNTRY <n> COUNTRY <n> This tells XlatList what country you are in. The cost table and the dialing table (see below) each have defaults for domestic and international calls. An international call is defined as one where the country code is different than your own. This defines what your own country code is. The default is "1" (United States) FIDO FIDO SEADOG SEADOG OPUS OPUS These tell XlatList who it is generating the node list for. The default is SEADOG. If you are using XlatList to generate a node list for a Fido BBS system, then your XLATLIST.CTL file should contain a FIDO statement. If you are generating a node list for an Opus system, or for a Fido system earlier than version 12, then your XLATLIST.CTL file sould contain an OPUS statement. The mode of operation of XlatList primarily controls the format of the NODELIST.BBS node list file that is created. The differences are as follows: o o In SEAdog mode, the generated node list covers your own zone only. Any HUB prefixes found in the St. Louis node list are retained, and any special prefixes defined in your XLATLIST.CTL file (with the HUB, IGATE, and OGATE statements) are added. Any ZONE prefixes found in the St. Louis node list are converted to REGION prefixes. o o In Opus mode, the generated node list is similar to that produced in SEAdog mode, except that special prefixes defined in your XLATLIST.CTL file are ignored. Node list entries with the HUB prefix will be preserved if in your own net, and removed otherwise. o o In Fido mode, the generated node list is similar to that produced in Opus mode, except that all zones will be included and the ZONE prefixes will be retained. SEAdog Page 3 XlatList USERLIST USERLIST INTERLIST INTERLIST NOUSERLIST NOUSERLIST These tell XlatList whether or not it should generate a directory of the users (sysops) listed in the node list. USERLIST says to generate a directory of users in your own zone. INTERLIST says to generate a directory of all users in all zones. NOUSERLIST says not to generate a directory, and is the default. The directory, if any, will be placed in a file called FIDOUSER.LST, and will be in a format suitable for use as a SEAdog user directory. Since a given node list may contain duplicate entries, XlatList will try to resolve the duplicates in an intelligent fashion. The exact method used by XlatList is somewhat complicated, but in general for any given name XlatList will try to: o Avoid listing an address that is marked DOWN or HOLD. o Avoid listing an address in another zone. o Give preference to an address in a network as opposed to an address in a region. o Avoid listing someone in their role as a host or hub. o Choose a higher baud rate over a lower one. o Give preference to an address that has continuous mail or extended protocol, while trying to avoid an address that is mail only. o All else being equal, select the lower node number. Based on some or all of the above criteria, and possibly on other criteria as well, XlatList will attempt to select the most suitable address to list for every name in the node list. You must have a copy of Ben Baker's QSORT program for the USERLIST or INTERLIST option to work. ADDR <address> <name> ADDR <address> <name> This statement is used to insert additional entries into the user directory, or to force XlatList to select a given address instead of what it would pick on its own. Any sort of address may be specified, including extended addresses. Some examples are: addr 1/0 Ben Baker addr 107/6.1 Thom Henderson addr 132/101!ncoast!lovell Dale Lovell SEAdog Page 4 XlatList FIDOPRN FIDOPRN FIDOTXT FIDOTXT NOFIDOLIST NOFIDOLIST These tell XlatList whether or not it should generate a human readable report on what nodes are in your node list. FIDOPRN says to generate a full 132 column report, which is placed in a file named NODELIST.PRN. FIDOTXT says to create an abbreviated 80 column report, which is placed in a file named NODELIST.TXT. NOFIDOLIST says not to generate any report at all, and is the default. Both the FIDOPRN and FIDOTXT statements may be given, in which case both reports are created. INDEX INDEX SINDEX SINDEX NOINDEX NOINDEX These tell XlatList whether or not it should add an index to the end of the Fido listing. Each line of the index identifies one net or region, and shows which page it is on. INDEX says to create the index in the order that the nets and regions were scanned. SINDEX says to sort the index by network number. NOINDEX says not to generate the index at all, and is the default. You must have a copy of Ben Baker's QSORT program in order for the SINDEX option to work properly. REPORT REPORT NOREPORT NOREPORT These tell XlatList whether or not it should print its report about how many nets, nodes, and so forth it scanned. NOREPORT says not to print the report. REPORT says to print it, and is the default. The report is printed at the end of the scan, when XlatList finshes scanning all node lists. The report can be redirected to a file or to the printer. COMMENTS COMMENTS NOCOMMENTS NOCOMMENTS These tell XlatList whether or not to display comments from the node list while compiling it. COMMENTS says to display them. NOCOMMENTS says not to, and is the default. All comments marked _ _ _ _ _ A, F, S, U, or ; are included. The comments may be redirected to the printer or to a file, along with the summary table printed by XlatList at the end of the run. SEAdog Page 5 XlatList DASH DASH NODASH NODASH These tell XlatList whether or not you want dashes stripped from the phone numbers in your NODELIST.BBS file. In some special cases the sequence of digits being dialed exceeds the forty character limit of Hayes-type modems. Stripping out the dashes shortens the number that must be dialed. NODASH says to strip out the dashes. DASH says to leave them in place, and is the default. ROUTE ROUTE NOROUTE NOROUTE These tell XlatList whether or not to create temporary data files for use by RouteGen. ROUTE says to create the files. NOROUTE says not to, and is the default. At present, the only temporary file created is NODELIST.FON. NODELIST NODELIST NONODELIST NONODELIST These tell XlatList whether or not to create a NODELIST.BBS file. NODELIST says to create it, and is the default. NONODELIST says not to create it. POINTS POINTS NOPOINTS NOPOINTS These tell XlatList whether or not to create node list entries for point net gateways. A point net gateway is signalled by a PN: flag in the comment field. For example, a St. Louis node list entry with a comment flag of "PN:2200" would be the public gateway to point net number 2200. Point net gateways are listed by adding HOST entries to the end of the generated node list. POINTS says to do this. NOPOINTS says not to do this, and is the default. MAXBAUD <baud> [<flag> <baud> . . .] MAXBAUD <baud> [<flag> <baud> . . .] This tells XlatList the maximum baud rate to allow in the node list. Any listed baud rate higher than <baud> will be set equal to <baud> in the NODELIST.BBS file. SEAdog Page 6 XlatList The basic maximum baud rate can be followed by any number of comment flag/alternate max baud rate pairs. For example, the statement: maxbaud 2400 HST 9600 would tell XlatList that the maximum baud rate to allow in the generated node list is 2400 baud, except that entries which have an HST flag may be listed as high as 9600 baud. Similarly: maxbaud 2400 HST 9600 ZAP 19200 would work the same, and in addition allow entries with a ZAP flag to be listed as high as 19200 baud. MYLIST <filename> ... MYLIST <filename> ... PVTLIST <filename> ... PVTLIST <filename> ... These tell XlatList the names of one or more St. Louis format node lists to be read in addition to (and after) the main node list. You would use these to add a private net to the main node list. You may have as many MYLIST and PVTLIST statements in your control file as you like, and they will be read in the order you give them. They differ in that lists named in a MYLIST statement are included in the reports created by the FIDOPRN and FIDOTXT statements, while lists named in a PVTLIST statement are not. PUBLIST <listname> [<diffname>] PUBLIST <listname> [<diffname>] XlatList normally looks for the public network list in a file called NODEDIFF.nnn, and looks for node list changes in a file called NODEDIFF.nnn (in each case the "nnn" is really a three digit number). The PUBLIST statement tells XlatList to use different names instead. The first argument is a name to look for for a node list, and the second is the name that is used for the corresponding difference file. If you only give the name for the node list, then XlatList will not look for a difference file. You may specify as many public lists as you like. For example, suppose that you normally compile your node list from files called REGION13.nnn and REGION10.nnn. The REGION13 list could come as a set of changes called R-13DIFF.nnn, but the REGION10 list is always distributed as a complete list. The statements to use would be: publist REGION13 R-13DIFF publist REGION10 If your XlatList control file does not contain any PUBLIST statements at all, then XlatList will act as if you had told it: publist NODELIST NODEDIFF SEAdog Page 7 XlatList CLEANUP CLEANUP When applying a difference file to a public node list, XlatList will normally leave all of the files around. Over time one can accumulate quite a backlog of old node lists and difference files. The CLEANUP statement tells XlatList to delete these old files ___ once they are no longer needed. The old files will not be deleted if the newly created file failed a CRC check. IGATE [<net>/]<node> ... IGATE [<net>/]<node> ... OGATE [<net>/]<node> ... OGATE [<net>/]<node> ... GATE [<net>/]<node> ... GATE [<net>/]<node> ... HUB [<net>/]<node> ... HUB [<net>/]<node> ... These are used to place SEAdog node list prefixes in a St. Louis format node list. Fido users will have no need of them. These have no effect in Fido mode. SEAdog users should, at a minimum, include an OGATE statement for their outbound host, if any. PHONE [<net>/]<node> <number> PHONE [<net>/]<node> <number> This is used to insert a phone number into the node list in place of one that is already there. For example, if the phone number given in the list for node 107/8 was "-Unpublished-", and you wanted to replace it with "1-201-472-8065", then you would say: PHONE 107/8 1-201-472-8065 If you do not specify a net number, then your own net (as defined in the NODE statement) is used. You may have as many PHONE statements as you like. You should always give phone numbers in their full form (as above) in order for other statements (such as DIAL) to work properly. BAUD [<net>/]<node> <baud> BAUD [<net>/]<node> <baud> This is used to insert a baud rate into the node list in place of one that is already there. For example, if node 107/8 was listed as being 1200 baud, but you wanted to send to him at 300 baud, then you would say: BAUD 107/8 300 If you do not specify a net number, then your own net (as defined in the NODE statement) is used. You may have as many BAUD statements as you like. SEAdog Page 8 XlatList OZONE <zone>:<net> [<newnet>] OZONE <zone>:<net> [<newnet>] This is used to insert nets from other zones into your own generated node list. For example, if you are in zone 1 but wish to have net 500 of zone 2 appear in your generated node list, then you would say: ozone 2:500 Remember that net numbers may be duplicated across zones. If your own zone already has a net 500, then you will need to use a different net number for the other net or it won't work right. For example, if you wanted net 500 of zone 2 to show up in your generated node list as net 3210, then you would say: ozone 2:500 3210 This statement has no effect in Fido mode. DIAL [<domestic> [<international>]] DIAL [<domestic> [<international>]] The DIAL statement marks the beginning of the dialing table. It can also take up to two optional arguments. The first argument is the default text to add to the phone number for all domestic calls, while the second is the default for international calls. Each entry in the dialing table consists of a partial phone number followed by a replacement string. The partial phone number is used to determine which replacements belong to which phone numbers. The table is scanned in sequence until an entry is found which matches the corresponding portion of the original phone number. If no table entries match the original phone number, then the appropriate default is used. This should be clearer in a moment. The replacement string can take any of the following forms: <prefix> <prefix>/<suffix> /<suffix> / The <prefix> is added to the beginning of the phone number, and the <suffix> is added to the end. When a default string is applied, this is all that happens. However, when a table entry is applied, the initial part of the phone number which matched the table is first stripped off. SEAdog Page 9 XlatList Here is an example of a dialing table: DIAL /-123 011- 1-201-472- 8- ;In house 1-201- / ;New Jersey END This table would cause the following translations: 1) 1-201-694-3348 would become 694-3348. Since it matches the "1-201-" entry, the initial "1-201-" gets stripped off. It's replacement string is specifying no prefix and no suffix. 2) 1-201-472-8065 would become 8-8065. As before, the matching digits are stripped off, but this time the replacement string is specifying a new prefix of "8-". Note that if the 1-201- entry had come first, it would have been applied instead. 3) 1-212-288-9076 does not match any table entry, so the default domestic string is used, and it becomes 1-212-288-9076-123. Since no table entry was used, no digits are stripped off. 4) 31-8380-37156 also does not match any table entries, but this number is in another country, so the international default is used, and it becomes 011-31-8380-37156. One last example. If you were in area code 201 and needed to dial a "9" for long distance instead of a "1", here is how you would do it: DIAL 1-201- ;Strip area code off local calls 1- 9- ;Prefix all else with a nine END SEAdog users may wish to use the equivalent DIAL statement in their CONFIG.DOG file instead. If the dialing table is used, then ___ the DIAL statement in the SEAdog configuration file should not be used, and vice versa. COST [<domestic> [<international>]] COST [<domestic> [<international>]] This statement marks the beginning of the cost table. A series of entries follows this statement, ending with an END statement. Up to two optional arguments may be supplied with the COST statement. The first argument is the default cost per message for domestic calls, and the second is the default cost per message for international calls. All costs are given in pennies. Each entry in the cost table consists of a partial phone number followed by a cost per message in pennies for calling that number, optionally followed by a maximum baud rate to use. The partial phone numbers are given in the same format as in the dialing table, and are scanned the same way. SEAdog Page 10 XlatList Here's an example of a typical COST table: cost 22 300 1-201-542- 20 ;Eatontown 1-201-750- 13 ;Woodbridge 1-201-963- 07 300 ;Jersey City 1-203- 20 ;Connecticut 1-301- 20 ;Maryland 1-503- 27 ;Oregon 1-602- 26 ;Arizona 1-703- 20 ;Virginia end INCLUDE <filename> INCLUDE <filename> This causes XlatList to read commands from the named file. When the end of the named file is reached, XlatList will resume reading the current file at the statement following the INCLUDE statement. Command Line Arguments Command Line Arguments You can override most of the XLATLIST.CTL control file statements by giving XlatList command line arguments when you run it. The following arguments change the operating mode: SEAdog SEAdog mode (default) FIDO Fido v12 mode OPUS Fido v11 / Opus mode The following arguments select different sorts of output: COMments Display node list comments. ROUte Create the ROUTEGEN data file. PRNlist Create a 132 column network report. TXTlist Create an 80 column network report. INDex Add an index to any network reports. SINdex Add a sorted index to any network reports. NODelist Create a NODELIST.BBS file. USErlist Create a domestic sysop directory. INTlist Create an international sysop directory. CLEanup Deletes old node lists and difference files. POInts Include point net gateways REPort Print a summary report The word "NO" anywhere on the command line causes all of the above which follow to be reversed in meaning. For example, if you wanted to run XlatList telling it to produce a RouteGen data file, but not to produce either of the network reports, you would type: xlatlist route no prnlist txtlist SEAdog Page 11 XlatList Case is unimportant. We've used capitals in the above lists to indicate the minimum abbreviation. For example, the previous example could also be typed: xlatlist rou no prn txt Finally, the FOR argument tells XlatList to use a different control file instead of the usual XLATLIST.CTL. For example, to run XlatList under the control of a file named LAPTOP.CTL, you would type: xlatlist for laptop Multiple zones Multiple zones _____ Zones are a high-order division of the FidoNet node list. Zones and countries are not related. A zone might contain several countries, and a country might contain several zones. Each zone is in effect its own node list. Mail traffic between the ____ ________ zones is provided by the zone gateways. Each zone's gateways to the other zones are listed near the beginning of the node list for that zone. This is not the place for an extended discussion of zones, zone gateways, and zone addressing. When XlatList processes a node list containing multiple zones, the NODELIST.BBS file it creates will contain only those nodes which are in your own zone, plus a few "administrative nodes" (such as the zone gateways) from each of the other zones. The user directory may include other zones or not, as you wish. This does not apply to Fido mode, as Fido mode is geared to Fido version 12 and later, which is able to handle a zone-based NODELIST.BBS file. SEAdog Page 12 XlatList ROUTEGEN ROUTEGEN RouteGen is a dedicated macro processor for use in creating routing files. In general, it passes along whatever was present in the input file, expanding any macros it finds along the way. In its normal mode of operation RouteGen reads routing commands from a control file called ROUTEGEN.CTL and places its output in a route file called ROUTE.DOG. This can be altered in several ways: 1) The /U command line switch (see below) can be used to change the name of the input file. In this case, the name of the output file also changes to match that of the new input file, but with an extension of ".DOG". 2) If RouteGen is placed in Opus mode, then the output file will be named ROUTE.CTL. 3) If RouteGen is placed in Fido mode, then instead of creating just one output file with an extension of ".DOG", RouteGen will create a separate route file for each schedule. The filename extension on each route file will match the schedule tag for the schedule it contains. 4) The FILE statement (see below) can be used to change the name (but not the extension) of the output file being created. You can have more than one FILE statement, allowing multiple sets of routing files to be created in one operation. RouteGen is invoked with a statement of the form: routegen [<address>] [/M] [/S] [/U<filename>] <address> is a network address, in either net/node format or zone:net/node format. RouteGen does not use the zone number, nor does it create interzone routing files at this time. The interzone address format is included only for compatibility with other programs. If an address is specified on the command line, then that address is used in the same way and for the same things as the NODE statement in a RouteGen control file. Note that a NODE statement overrides any address that may be given on the command line. SEAdog Page 13 RouteGen RouteGen also understands the following command line options: /U<filename> This names an alternate control file to use instead of ROUTEGEN.CTL. If no extension is given, then ".CTL" is assumed. The output file created by RouteGen will have the same name as the alternate control file (but a different extension). When __ ___ operating RouteGen in Opus mode do not use a control file named ROUTE.CTL. /F This tells RouteGen to operate in Fido mode, as opposed to its default SEAdog mode. Note that a SEADOG or OPUS statement in the control file overrides this option. /O This tells RouteGen to operate in Opus mode, as opposed to its default SEAdog mode. Note that a SEADOG or FIDO statement in the control file overrides this option. /S This tells RouteGen to operate in SEAdog mode, which is its default state anyway. This option is included for completeness. /M This causes RouteGen to display status information about its memory usage. This can be useful for determining how a routing file got to be too complex. See the section on advice and tips later in this manual. /T This causes RouteGen to dump its symbol table at the end of the run. We're not sure what good this would do you, but you might find it interesting. Option switches may be given in either uppercase or lowercase, and may begin with either a slash or a dash. They may also be bunched together as long as the /U switch comes last. For example, if you wanted to run RouteGen on a control file named WASTE.CTL, and you wanted to see memory usage and the symbol table, you could type: routegen -msuwaste RouteGen reads its control file line by line, and expects each line to begin with a keyword followed by all of its arguments. There are two general categories of keywords: o Control verbs o Control verbs; These are used to control RouteGen itself, and will be described in detail below. o Routing verbs o Routing verbs; These are the actual routing commands to the mailer you are using, and are specific to it. They should be described in its documentation. We will not attempt to document them here. SEAdog Page 14 RouteGen Routing verbs are usually followed by a list of network addresses. The purpose of RouteGen is to make it easier to create and maintain those lists of network addresses. RouteGen recognizes the following classes of routing verbs: o Targeted verbs o Targeted verbs; These are routing instructions whose first argument must be a single network address that is the target of the routing action, possibly followed by a list of network addresses that are the object of the routing action. The following targeted verbs are currently defined: Route-to Arcdirect Archold Arccm o Argmented verbs o Argmented verbs; These are routing instructions whose first argument is something other than a network address, possibly followed by a list of network addresses to which it applies. The following argumented instructions are currently defined: Script Password Redial o Schedule statements o Schedule statements; Right now the Schedule statement is a special case all unto itself. Maybe someday we can make a general class out of it. When operating in Fido mode it is a fatal error to have any such statement before the first SCHEDULE statement, or between the previous FILE statement and its following SCHEDULE statement. o Everything else o Everything else; Anything that isn't one of the above is the general case. RouteGen will consider it to consist of a one word keyword followed by a list of network addresses. The majority of routing instructions fall into this category. Any routing verb may be prefaced with the DON'T keyword. The DON'T keyword is passed through literally by RouteGen. Please check the documentation for your mailer to determine what routing verbs (if any) may be prefaced with DON'T. SEAdog Page 15 RouteGen In general any routing verb may be followed by a list of network addresses. Such a list consists of zero or more of the following: <net>/<node> The address of any given node. <node> The address of another node in your own network. <net>/<lo>:<hi> A list of all nodes in the specified range. <lo>:<hi> A list of all nodes in the specified range in your own network. "<literal>" A quoted literal string. <macro> A macro defining some list of addresses. Most of the power of RouteGen comes from the use of macros. You can define your own macros by use of the DEFINE and ALSO statements (described later). RouteGen also has many predefined macros built in. They are as follows: NET-nnn NET-nnn REGION-nnn REGION-nnn These are equivalent, and are replaced with all of the nodes in the given net. Example: No-route net-103 AREA-aaa[-eee[:eee][,eee[:eee]...] AREA-aaa[-eee[:eee][,eee[:eee]...] This is replaced with all of the nodes whose phone numbers begin with "1-aaa-", or with "1-aaa-eee-" if an exchange is specified. Multiple exchanges may be specified, and ranges of exchanges may be given. Example: Send-to area-201 Hold area-201 except area-201-472:474,694,776:778 SEAdog Page 16 RouteGen COUNTRY-c[-aaa[-eee[:eee][,eee[:eee]]]] COUNTRY-c[-aaa[-eee[:eee][,eee[:eee]]]] This is replaced with all of the nodes whose phone numbers begin with "c", or with "c-aaa-" if an area code is specified, or with "c-aaa-eee-" if both an area code and an exchange are specified. Note that "COUNTRY-1-201" is equivalent to "AREA-201". Multiple exchanges and ranges of exchanges may be specified as with the AREA macro. Example: Hold country-51 FLAG-<x> FLAG-<x> TAG-<x> TAG-<x> These are equivalent, and are replaced with all of the nodes whose node list entries contain the string <x>. Neither case nor position is important. For example, "flag-XP" would be replaced by a list of all nodes which contain the string "XP" anywhere in their flags field. The flags field is the rightmost column of the wide Fido report produced by XlatList. Example: Send-to flag-#CM HUB-<node> HUB-<node> HUB-<net/node> HUB-<net/node> This is replaced by all of the nodes whose hub (as specified in the St. Louis format node list) is the named node. The hub node is included in the list. If you do not specify a net, then your own net is assumed. For example, "hub-300" would be replaced by a list of all nodes in your own net who have node 300 in your net as their hub. Example: Forward-for hub-200 LIST-<filename> LIST-<filename> This is replaced by all of the nodes referred to in the specified file. Any word in the file which "looks like" a network address (two numbers separated by a slash) will be included in the list. All other words are ignored. This is specifically designed to allow the use of "AREAS.BBS" in creating route files. Example: No-route list-AREAS.BBS SEAdog Page 17 RouteGen BAUD-<rate> BAUD-<rate> This is replaced by a list of all nodes which are listed at the given baud rate. Only nodes whose listed baud rate in the node list exactly matches the rate stated will be listed. Nodes with higher or lower baud rates will not be included. Example: Send-to baud-9600 AKA-<node> AKA-<node> AKA-<net>/<node> AKA-<net>/<node> ALTER-<node> ALTER-<node> ALTER-<net>/<node> ALTER-<net>/<node> These are equivalent, and are replaced by the alternate address of the specified node. If you do not specify a network number, then your own network is assumed. The specified node must have an AKA: flag in the comment flags field of his St. Louis node list entry. For example, suppose that node 107/300 has the comment flag "AKA:312" in his node list entry. In that case, the statement: Hold aka-107/300 would be replaced by: Hold 107/312 As an example of usage, suppose that all nodes under the hub 107/300 are supposed to hold their mail for pickup by 107/300. ____ But "107/300" is the hub's alternate address -- his real address is 107/312. So in his node list entry he puts an "AKA:312", and all the nodes under him use the routing statements: Schedule B Route-to aka-300 ALL Send-to aka-300 Hold aka-300 ALL ALL This is replaced with all of the nodes in the net. If possible, it will be abbreviated to the short form, "ALL". Example: Give-to all SEAdog Page 18 RouteGen A <list> may contain the keywords EXCEPT and AND. These are used as follows: <list1> EXCEPT <list2> results in a list of all addresses given in <list1> which are not also given in <list2>. <list1> AND <list2> results in a list of all addresses given in <list1> which are also given in <list2>. <list1> AND <list2> AND <list3> results in a list of all addresses which are given in all three lists. EXCEPT and AND may be used together, in which case EXCEPT is evaluated first. For example: <list1> EXCEPT <list2> AND <list3> results in a list of all addresses given in both <list1> and <list3>, but not in <list2>. ___ You should not use EXCEPT in conjunction with metanodes like OURNET, HOSTS, and so forth (except for the ALL metanode, see above). Metanodes are not translated by RouteGen, so saying something like: ournet except 107/3 will not work as you might expect. Use the equivalent macro in RouteGen instead. SEAdog Page 19 RouteGen RouteGen Control Verbs RouteGen Control Verbs We will now describe in detail the control verbs which are used to control how RouteGen works and what it does. As before, each statement is one line consisting of the control verb followed by its arguments. The following control verbs are currently defined: NODE <net>/<node> NODE <net>/<node> NODE <zone>:<net>/<node> NODE <zone>:<net>/<node> This tells RouteGen what your network address is. If you use any of the conditional statements (see below), then you should be careful to ensure that you have the correct address here. Otherwise, it is sufficient if the net number is correct. RouteGen makes no use of the zone number, nor can RouteGen create interzone routing files. The interzone format is provided solely for compatibility with other programs. SEADOG SEADOG FIDO FIDO OPUS OPUS These tell RouteGen what mode to operate in. FIDO says to tailor the output to the needs of the Fido BBS system. OPUS says to tailor the output to the needs of the OMMM packetizer. SEADOG says to tailor it to the SEAdog Electronic Mail system, and is the default. FILE <name> FILE <name> This tells RouteGen what name to use on future output files. It also causes the current output file to be closed. In SEADOG mode it causes the next output file to be opened immediately with an extension of ".DOG". In OPUS mode it causes the next output file __ _______ to be opened immediately with an extension of ".CTL". Be careful when picking a file name while operating in OPUS mode, or you might trash another control file. INCLUDE <name> INCLUDE <name> This tells RouteGen to read additional routing instructions from the named file. If no extension is specified, ".CTL" is assumed. When the end of the named file is reached RouteGen will resume reading the current file at the statement after the INCLUDE statement. The file being included may include additional files, __ _________ which may include more files, ad infinitum (limited only by memory). SEAdog Page 20 RouteGen DEFINE <name> <list> DEFINE <name> <list> This is used to define your own macros, and is quite powerful. The <list> is translated immediately, and all future references to <name> will be replaced with the list. The entire definition must fit on one line, but you can define macros in terms of themselves and other macros, so the resulting list can be quite large indeed. See also the ALSO command, below. ALSO <list> ALSO <list> This is used to add to the definition of the previously defined macro, thus allowing macro definitions to span more than one line. For example: define big 107/100 107/200 107/300 also 107/400 107/500 The first statement defines a macro called BIG as meaning a list of the three given addresses. The second line adds two more addresses to the definition of BIG, resulting in a macro called BIG that means a list of all five addresses. You may have as many ALSO statements as you like that memory constraints will allow. SCHEDULE <tag> [<list>] SCHEDULE <tag> [<list>] In Fido mode this causes the current output file to be closed, and a new one opened with an extension of ".<tag>". In SEAdog mode the current output file is kept. Any macros in the <list> are expanded, and the resulting SCHEDULE statement is output. DISPLAY <list> DISPLAY <list> This causes the network addresses comprising the <list> to be displayed on the screen. NULL <list> NULL <list> This causes the network addresses comprising the <list> to be written to the output file with no keyword. This can be handy for creating mailing lists. IF <condition> IF <condition> IF NOT <condition> IF NOT <condition> This is used to make parts of a RouteGen control file conditional. This will only work when you are using a ".FON" file created by XlatList (using the "ROUTE" control statement, q.v.), otherwise the condition is undefined. The <condition> depends on your own SEAdog Page 21 RouteGen node number, as specified in the "NODE" statement or on the command used to invoke RouteGen. If you have not defined your own network address, then the results are undefined. The following conditionals are currently defined: IGATE IGATE True if you are the inbound gateway for your network. HOST HOST Same as IGATE. Note that FidoNet hosts are sensibly equivalent to SEAdog inbound gateways. OGATE OGATE True if you are the outbound gateway for your network. Not defined in Fido mode. HUB HUB True if you are a hub in your network. Not defined in Fido mode. LOCAL LOCAL True if you are none of the above. NODE <list> NODE <list> True if you are a member of <list>, where <list> is a list of one or more nodes. ANY <list> ANY <list> True if the specified list contains any addresses. FLAG <xx> FLAG <xx> True if your own node list entry has <xx> in its comment flags field. TAG <xx> TAG <xx> Same as FLAG. SEADOG SEADOG True if RouteGen is currently in SEAdog mode. FIDO FIDO True if RouteGen is currently in Fido mode. OPUS OPUS True if RouteGen is currently in Opus mode. Preceding any of these with the keyword NOT reverses the logic of the test. For example: if not any net-103 is true only if there are no nodes in network 103. ELSE [<statement>] ELSE [<statement>] This signals the converse of a previous IF. The statement following the word ELSE is optional. If it is given, then no ENDIF is required. ENDIF ENDIF This signals the end of a previous IF statement. SEAdog Page 22 RouteGen ROUTEGEN CONDITIONALS ROUTEGEN CONDITIONALS The IF, ELSE, and ENDIF statements all work together pretty much as you'd expect, and may be nested as deeply as you like that memory constraints will allow. Here's an example of the use of conditionals: if host forward-to ournet else if ogate forward-for ournet else if hub if node 100 forward-to 100:199 else if node 200 forward-to 100:299 else if node 300 forward-to 300:399 else if node 400 if any 400:499 forward-to 400:499 endif endif else poll 100 The ELSE statement can take any of three basic forms. Whether or not an ENDIF will be required depends on which form of ELSE is used, as follows: 1) ELSE An ENDIF will be required. 2) ELSE IF An ENDIF will be required, unless another ELSE clause follows this one. 3) ELSE <statement> An ENDIF is not required. This sounds strange, but with any luck it'll be intuitively obvious. SEAdog Page 23 RouteGen NODE LIST SIZE LIMITS NODE LIST SIZE LIMITS XlatList has no limit on the size of the node list that it can process. It handles a node list in serial fashion, and can thus properly handle a list of any size. ____ RouteGen, on the other hand, does have an upper limit on the size of the node list which it can handle. By the very nature of what it is doing, it must be able to create and use a table of all of the nodes in the node list. At this time that table is kept in memory for reasons of speed. There are no provisions for spooling the table to disk if it grows too large to hold in memory. Table space is dynamically allocated as it is needed, so there is no defined upper limit. Instead, it is limited by the total amount of memory which is available when RouteGen is run. RouteGen will abort with an error message if the node list is too large to process. In addition, as macros are defined they too are held in memory. It is quite possible for a routing control file of modest length to define macros of such size that they cannot all be held in memory at one time. RouteGen will abort with an error message if the routing control file is too complex to process. You should try to avoid creating route files that define very large macros. By this we mean macros which evaluate to a very long list of nodes. In particular, if your route file contained: define st-louis net-100 1/0 1/2 1/107 define outbound 100/10 define world all except st-louis schedule c send-to outbound route-to outbound world schedule d send-to world route-to outbound world it may work, but it probably isn't a good idea. In this particular case, the macro "world" is being defined as a very large list of nodes. A large list like this has the following disadvantages: 1) It requires a lot of memory to define. 2) It takes a fair amount of processor time to define. 3) It will generate a very large route file, which will consume much disk space. 4) It will take longer for your mail server to set up a mail event, since it will have to scan and process a very large route file. SEAdog Page 24 RouteGen Here's a better way to get the same result: define st-louis net-100 1/0 1/2 1/107 define outbound 100/10 schedule c send-to outbound route-to outbound ALL no-route st-louis schedule d send-to ALL route-to outbound ALL don't send-to st-louis This example uses the keyword "ALL", but "ALL" isn't expanded unless you use the "ALL EXCEPT" construct. "ALL EXCEPT" is perfectly legal, but as a general rule you should try to avoid using it. If you are using SEAdog, then here's another trick you can use: define st-louis net-100 1/0 1/2 1/107 define outbound 100/10 schedule c send-to outbound route-to outbound ALL except st-louis schedule d send-to ALL route-to outbound ALL except st-louis In this case RouteGen will treat the EXCEPT as a routing verb, and thus not expand the ALL keywords. SEAdog, on the other hand, does not read the routing file in a line-by-line fashion, and will thus properly execute the commands. SEAdog Page 25 RouteGen LIMITED WARRANTY IMPORTANT NOTICE: IMPORTANT NOTICE: Any use of this software for any period of time for any purpose whatsoever constitutes your unqualified acceptance of this LICENSE and subjects you to all of the terms and conditions set forth below: System Enhancement Associates, Inc. ("SEA") warrants to any Licensee that acquires the program from SEA or an authorized SEA representative ONLY that: 1) All diskettes SEA provides constitute an accurate duplication of the software and SEA will replace any diskette found to be defective within 30 days from date of acquisition. SEA will not honor this warranty if the diskette has been subjected to physical abuse, or used in defective or non-compatible equipment. 2) SEA's software will perform substantially as described in the documentation SEA regularly supplies with that software, if operated as prescribed in such documentation including the hardware and software environment specified. 3) If a significant defect in any program is found, Licensee's only remedy shall be to receive refund of the actual fee Licensee paid for such defective program. In no event will such a refund exceed the fee SEA charges for such program. 4) SEA makes no warranty or representation that the software will be error free nor that its use by Licensee will be uninterrupted. Except as provided above, SEA disclaims all other warranties, either express or implied, including but not limited to any implied warranty of merchantability or fitness for any particular purpose. Licensee agrees to take full responsibility for the selection of and any use whatsoever made of the software. IN NO EVENT WILL SEA BE LIABLE FOR ANY DAMAGES WHATSOEVER (INCLUDING WITHOUT LIMITATION DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION OR THE LIKE) ARISING OUT OF THE USE OF, INTERRUPTION IN THE USE OF, OR INABILITY TO USE THIS SOFTWARE, EVEN IF SEA HAS BEEN ADVISED OF ANY POSSIBILITY OR LIKELYHOOD OF SUCH DAMAGES. SEAdog Page 26 Warranty